.TH std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl, \- std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl,

.SH Synopsis

   Defined in header <cmath>
   Rounding to floating-point
   types
   float       round ( float num
   );

   double      round ( double num          \fI(since C++11)\fP
   );                                      (until C++23)

   long double round ( long double
   num );
   constexpr /*
   floating-point-type */                  (since C++23)
               round ( /*
   floating-point-type */ num );
   float       roundf( float num           \fI(since C++11)\fP
   );                                  \fB(2)\fP (constexpr
                                           since C++23)
   long double roundl( long double         \fI(since C++11)\fP
   num );                              \fB(3)\fP (constexpr
                                           since C++23)
   Rounding to long
   long lround ( float num );

   long lround ( double num );                            \fI(since C++11)\fP
                                                          (until C++23)
   long lround ( long double num
   );
   constexpr long lround( /*                              (since C++23)
   floating-point-type */ num );
                                                          \fI(since C++11)\fP
   long lroundf( float num );              \fB(5)\fP            (constexpr
                                                          since C++23)
   long lroundl( long double num   \fB(1)\fP                    \fI(since C++11)\fP
   );                                      \fB(6)\fP            (constexpr
                                                          since C++23)
   Rounding to long long
   long long llround ( float num
   );

   long long llround ( double num                                        \fI(since C++11)\fP
   );                                                                    (until C++23)
                                       \fB(4)\fP
   long long llround ( long double
   num );
   constexpr long long llround( /*                                       (since C++23)
   floating-point-type */ num );
   long long llroundf( float num                                         \fI(since C++11)\fP
   );                                                     \fB(8)\fP            (constexpr
                                                                         since C++23)
   long long llroundl( long double         \fB(7)\fP                           \fI(since C++11)\fP
   num );                                                 \fB(9)\fP            (constexpr
                                                                         since C++23)
   Additional overloads
   Defined in header <cmath>
   template< class Integer >                                             \fI(since C++11)\fP
   double round( Integer num );                           (A)            (constexpr
                                                                         since C++23)
   template< class Integer >                                             \fI(since C++11)\fP
   long lround( Integer num );                            (B)            (constexpr
                                                                         since C++23)
   template< class Integer >                                             \fI(since C++11)\fP
   long long llround( Integer num                         (C)            (constexpr
   );                                                                    since C++23)

   1-3) Computes the nearest integer value to num (in floating-point format), rounding
   halfway cases away from zero, regardless of the current rounding mode.
   The library provides overloads of std::round for all cv-unqualified floating-point
   types as the type of the parameter num.
   (since C++23)
   4-9) Computes the nearest integer value to num (in integer format), rounding halfway
   cases away from zero, regardless of the current rounding mode.
   The library provides overloads of std::lround and std::llround for all
   cv-unqualified floating-point types as the type of the parameter num.
   (since C++23)
   A-C) Additional overloads are provided for all integer types, which are treated as
   double.

.SH Parameters

   num - floating-point or integer value

.SH Return value

   If no errors occur, the nearest integer value to num, rounding halfway cases away
   from zero, is returned.

.SH Return value
   math-round away zero.svg
   num

   If a domain error occurs, an implementation-defined value is returned.

.SH Error handling

   Errors are reported as specified in math_errhandling.

   If the result of std::lround or std::llround is outside the range representable by
   the return type, a domain error or a range error may occur.

   If the implementation supports IEEE floating-point arithmetic (IEC 60559),

   For the std::round function:
     * The current rounding mode has no effect.
     * If num is ±∞, it is returned, unmodified.
     * If num is ±0, it is returned, unmodified.
     * If num is NaN, NaN is returned.
   For std::lround and std::llround functions:
     * FE_INEXACT is never raised.
     * The current rounding mode has no effect.
     * If num is ±∞, FE_INVALID is raised and an implementation-defined value is
       returned.
     * If the result of the rounding is outside the range of the return type,
       FE_INVALID is raised and an implementation-defined value is returned.
     * If num is NaN, FE_INVALID is raised and an implementation-defined value is
       returned.

.SH Notes

   FE_INEXACT may be (but is not required to be) raised by std::round when rounding a
   non-integer finite value.

   The largest representable floating-point values are exact integers in all standard
   floating-point formats, so std::round never overflows on its own; however the result
   may overflow any integer type (including std::intmax_t), when stored in an integer
   variable.

   POSIX specifies that all cases where std::lround or std::llround raise FE_INEXACT
   are domain errors.

   The double version of std::round behaves as if implemented as follows:

 #include <cfenv>
 #include <cmath>

 #pragma STDC FENV_ACCESS ON

 double round(double x)
 {
     const int save_round = std::fegetround();
     std::fesetround(FE_TOWARDZERO);
     const double result = std::rint(std::copysign(0.5 + std::fabs(x), x));
     std::fesetround(save_round);
     return result;
 }

   The additional overloads are not required to be provided exactly as (A-C). They only
   need to be sufficient to ensure that for their argument num of integer type:

     * std::round(num) has the same effect as std::round(static_cast<double>(num)).
     * std::lround(num) has the same effect as std::lround(static_cast<double>(num)).
     * std::llround(num) has the same effect as std::llround(static_cast<double>(num)).

.SH Example


// Run this code

 #include <cassert>
 #include <cfenv>
 #include <cfloat>
 #include <climits>
 #include <cmath>
 #include <iostream>

 // #pragma STDC FENV_ACCESS ON

 double custom_round(double x)
 {
     const int save_round = std::fegetround();
     std::fesetround(FE_TOWARDZERO);
     const double result = std::rint(std::copysign(0.5 + std::fabs(x), x));
     std::fesetround(save_round);
     return result;
 }

 void test_custom_round()
 {
     for (const double x :
         {
             0.0, 0.3,
             0.5 - DBL_EPSILON / 2,
             0.5,
             0.5 + DBL_EPSILON / 2,
             0.7, 1.0, 2.3, 2.5, 2.7, 3.0,
             static_cast<double>(INFINITY)
         })
         assert(round(+x) == custom_round(+x) && round(-x) == custom_round(-x));
 }

 int main()
 {
     test_custom_round();

     std::cout << std::showpos;

     // round
     std::cout << "round(+2.3) = " << std::round(2.3)
               << "  round(+2.5) = " << std::round(2.5)
               << "  round(+2.7) = " << std::round(2.7) << '\\n'
               << "round(-2.3) = " << std::round(-2.3)
               << "  round(-2.5) = " << std::round(-2.5)
               << "  round(-2.7) = " << std::round(-2.7) << '\\n';

     std::cout << "round(-0.0) = " << std::round(-0.0)  << '\\n'
               << "round(-Inf) = " << std::round(-INFINITY) << '\\n';

     // lround
     std::cout << "lround(+2.3) = " << std::lround(2.3)
               << "  lround(+2.5) = " << std::lround(2.5)
               << "  lround(+2.7) = " << std::lround(2.7) << '\\n'
               << "lround(-2.3) = " << std::lround(-2.3)
               << "  lround(-2.5) = " << std::lround(-2.5)
               << "  lround(-2.7) = " << std::lround(-2.7) << '\\n';

     std::cout << "lround(-0.0) = " << std::lround(-0.0)  << '\\n'
               << "lround(-Inf) = " << std::lround(-INFINITY) << '\\n';

     // error handling
     std::feclearexcept(FE_ALL_EXCEPT);

     std::cout << "std::lround(LONG_MAX+1.5) = "
               << std::lround(LONG_MAX + 1.5) << '\\n';
     if (std::fetestexcept(FE_INVALID))
         std::cout << "    FE_INVALID was raised\\n";
 }

.SH Possible output:

 round(+2.3) = +2  round(+2.5) = +3  round(+2.7) = +3
 round(-2.3) = -2  round(-2.5) = -3  round(-2.7) = -3
 round(-0.0) = -0
 round(-Inf) = -inf
 lround(+2.3) = +2  lround(+2.5) = +3  lround(+2.7) = +3
 lround(-2.3) = -2  lround(-2.5) = -3  lround(-2.7) = -3
 lround(-0.0) = +0
 lround(-Inf) = -9223372036854775808
 std::lround(LONG_MAX+1.5) = -9223372036854775808
     FE_INVALID was raised

.SH See also

   floor
   floorf  nearest integer not greater than the given value
   floorl  \fI(function)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   ceil
   ceilf   nearest integer not less than the given value
   ceill   \fI(function)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   trunc
   truncf
   truncl  nearest integer not greater in magnitude than the given value
   \fI(C++11)\fP \fI(function)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   C documentation for
   round
